using AdmissionQA.Application.Common;
using AdmissionQA.Application.Dtos.ScholarshipInfo;
using AdmissionQA.Domain.Entities;

namespace AdmissionQA.Application.ServiceInterfaces;

/// <summary>
/// 奖学金信息服务接口
/// </summary>
public interface IScholarshipInfoServices
{
    /// <summary>
    /// 创建奖学金信息
    /// </summary>
    /// <param name="scholarshipInfo">奖学金信息</param>
    /// <returns>创建结果</returns>
    Task<Result<string>> CreateScholarshipInfoAsync(ScholarshipInfoDto scholarshipInfo);

    /// <summary>
    /// 批量创建奖学金信息
    /// </summary>
    /// <param name="scholarshipInfos">奖学金信息列表</param>
    /// <returns>创建结果</returns>
    Task<Result<string>> CreateScholarshipInfosAsync(ScholarshipInfosDto scholarshipInfos);

    /// <summary>
    /// 根据ID获取奖学金信息
    /// </summary>
    /// <param name="id">奖学金信息ID</param>
    /// <returns>奖学金信息</returns>
    Task<Result<ScholarshipInfo>> GetScholarshipInfoByIdAsync(Guid id);

    /// <summary>
    /// 获取所有奖学金信息
    /// </summary>
    /// <returns>奖学金信息列表</returns>
    Task<Result<IEnumerable<ScholarshipInfo>>> GetAllScholarshipInfosAsync();

    /// <summary>
    /// 分页获取奖学金信息
    /// </summary>
    /// <param name="pageIndex">页码</param>
    /// <param name="pageSize">页大小</param>
    /// <returns>分页结果</returns>
    Task<Result<IEnumerable<ScholarshipInfo>>> GetPagedScholarshipInfosAsync(
        int pageIndex = 0,
        int pageSize = 10
    );

    /// <summary>
    /// 根据名称搜索奖学金信息
    /// </summary>
    /// <param name="scholarshipName">奖学金名称</param>
    /// <returns>匹配的奖学金信息列表</returns>
    Task<Result<IEnumerable<ScholarshipInfo>>> SearchScholarshipInfosByNameAsync(
        string scholarshipName
    );

    /// <summary>
    /// 更新奖学金信息
    /// </summary>
    /// <param name="id">奖学金信息ID</param>
    /// <param name="scholarshipInfo">奖学金信息</param>
    /// <returns>更新结果</returns>
    Task<Result<string>> UpdateScholarshipInfoAsync(Guid id, ScholarshipInfoDto scholarshipInfo);

    /// <summary>
    /// 删除奖学金信息
    /// </summary>
    /// <param name="id">奖学金信息ID</param>
    /// <returns>删除结果</returns>
    Task<Result<string>> DeleteScholarshipInfoAsync(Guid id);

    /// <summary>
    /// 批量删除奖学金信息
    /// </summary>
    /// <param name="ids">奖学金信息ID列表</param>
    /// <returns>删除结果</returns>
    Task<Result<string>> DeleteScholarshipInfosAsync(IEnumerable<Guid> ids);

    /// <summary>
    /// 获取奖学金信息总数
    /// </summary>
    /// <returns>奖学金信息总数</returns>
    Task<int> GetScholarshipInfoCountAsync();

    /// <summary>
    /// 基于向量相似度搜索奖学金信息
    /// </summary>
    /// <param name="text">查询文本</param>
    /// <param name="topK">返回最相似的前K个</param>
    /// <returns>最相似的奖学金信息列表</returns>
    Task<Result<IEnumerable<ScholarshipInfo>>> SearchScholarshipInfosByEmbeddingAsync(string text, int topK = 5);
}
